%
% Copyright (c) 2010,2013 LAAS/CNRS
% All rights reserved.
%
% Permission to use, copy, modify, and distribute this software for any purpose
% with or without   fee is hereby granted, provided   that the above  copyright
% notice and this permission notice appear in all copies.
%
% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
% REGARD TO THIS  SOFTWARE INCLUDING ALL  IMPLIED WARRANTIES OF MERCHANTABILITY
% AND FITNESS. IN NO EVENT SHALL THE AUTHOR  BE LIABLE FOR ANY SPECIAL, DIRECT,
% INDIRECT, OR CONSEQUENTIAL DAMAGES OR  ANY DAMAGES WHATSOEVER RESULTING  FROM
% LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
% OTHER TORTIOUS ACTION,   ARISING OUT OF OR IN    CONNECTION WITH THE USE   OR
% PERFORMANCE OF THIS SOFTWARE.
%
%                                             Anthony Mallet on Wed Oct  6 2010
%
\section{Package files, directories and contents} % ------------------------
\label{section:pkgvars}

Whenever you're preparing a package, there are a number of files involved which
are described in the following sections.

\subsection{Makefile} % ----------------------------------------------------
\label{subsection:makefile}

Building, installation and creation of a package are all controlled by the
package's Makefile. The Makefile describes various things about a package,
for example from where to get it, how to configure, build, and install it.

A package Makefile contains several sections that describe the package.

In the first section there are the following variables, which should appear
exactly in the order given here. The order and grouping of the variables is
mostly historical and has no further meaning.

\begin{description}
   \item[PKGREVISION] Defines the \robotpkg revision number of the package. This
   {\em should not be set} for a new package. See
   \xref{section:genvars:PKGREVISION}{Section~\ref{section:genvars:PKGREVISION}}
   for details.

   \smallbreak
   \item[MASTER\_SITES] In simple cases, {\tt MASTER\_SITES}  defines all URLs
   from where the distfile, whose name is derived from the {\tt DISTNAME}
   variable, is fetched.

   When actually fetching the distfiles, each item from {\tt MASTER\_SITES}
   gets the name of each distfile appended to it, without an intermediate
   slash. Therefore, all site values have to end with a slash or other
   separator character. This allows for example to set {\tt MASTER\_SITES} to a
   URL of a CGI script that gets the name of the distfile as a parameter. In
   this case, the definition would look like:
   \begin{quote}
      {\tt MASTER\_SITES=   http://www.example.com/download.cgi?file=}
   \end{quote}

   There are some predefined values for {\tt MASTER\_SITES}, which can be used
   in packages. The names of the variables should speak for themselves.
   \begin{quote}\tt
      \$\{MASTER\_SITE\_SOURCEFORGE\}\\
      \$\{MASTER\_SITE\_GNU\}\\
      \$\{MASTER\_SITE\_OPENROBOTS\}
   \end{quote}

   If you choose one of these predefined sites, you may want to specify a
   subdirectory of that site. Since these macros may expand to more than one
   actual site, {\em you must} use the following construct to specify a
   subdirectory:
   \begin{quote}\tt
      MASTER\_SITES=~\$\{MASTER\_SITE\_SOURCEFORGE:=project\_name/\}
   \end{quote}
   Note the trailing slash after the subdirectory name.

   \smallbreak
   \item[FETCH\_METHOD] This is the method used to download the distfile from
   {\tt MASTER\_SITES}. It defaults to '{\tt archive}' which corresponds to the
   normal situation where distfile is an archive available from {\tt
   MASTER\_SITES}, so it normally needs not to be set.

   However, it can happen that a software provider does not provide any archive
   available for download but has only a public repository. In this case, {\tt
   FETCH\_METHOD} can be set to {\tt cvs}, {\tt git} or {\tt svn} according to
   the kind of repository available. {\tt MASTER\_SITES} is then interpreted as
   a repository of the form {\tt url[@revision[+module]]}, where the bits
   between square brackets are optional and refer to a particular revision and
   module in the repository located at {\tt url}. {\tt url} can take any form
   supported by the underlying fetch tool ({\tt cvs}, {\tt git} or {\tt
   svn}). It is {\em strongly} advised to define at least a specific revision
   to be checked out, so that the package can be reproducibly installed in a
   known state.

   \smallbreak
   \item[MASTER\_REPOSITORY] defines a VCS repository from where a ``{\tt make
   checkout}'' will download the latest revision of a software. {\tt
   MASTER\_REPOSITORY} is a list of 2 or 3 elements. The first element is the
   VCS tool to be used: it must be one of {\tt cvs}, {\tt git} or {\tt svn}.
   The second element is the location of the repository. It must be written in
   a syntax understood by the actual VCS tool. The third optional element is a
   list of specific elements to be checked out instead of the default (the
   whole repository).

   \smallbreak
   \item[CHECKOUT\_VCS\_OPTS] is a list of options used when fetching a
   package via a {\tt make checkout} command. The options are passed to the
   ``cvs checkout'', ``git clone'' or ``svn checkout'' command that extract the
   source archive.
\end{description}

The second section contains information about separately downloaded patches, if any.

\begin{description}

   \item[PATCHFILES] Name(s) of additional files that contain distribution
   patches distributed by the author or other maintainers. There is no
   default. robotpkg will look for them at {\tt    PATCH\_SITES}. They will
   automatically be uncompressed before patching if    the names end with .gz
   or .Z.

   \smallbreak
   \item[PATCH\_SITES] Primary location(s) for distribution patch files (see
   {\tt PATCHFILES} above) if not found locally.

\end{description}

The third section contains the following variables.

\begin{description}

   \item[MAINTAINER] is the email address of the person who feels responsible
   for this package, and who is most likely to look at problems or questions
   regarding this package. Other developers may contact the {\tt MAINTAINER}
   before making changes to the package, but are not required to do so. When
   packaging a new program, set {\tt MAINTAINER} to yourself. If you really
   can't maintain the package for future updates, set it to
   {\tt \string<robotpkg@laas.fr\string>}.

   \smallbreak
   \item[HOMEPAGE] is a URL where users can find more information about the
   package.

   \smallbreak
   \item[COMMENT] is a one-line description of the package (should not include
   the package name).

   \smallbreak
   \item[LICENSE] Denoting that a package may be installed and used according
   to a particular license is done by placing the license in {\tt
   robotpkg/licenses} and setting the LICENSE variable to a string identifying
   the license file, e.g. in {\tt shell/eltclsh}:
   \begin{quote}
      LICENSE=		2-clause-bsd
   \end{quote}

   The license tag mechanism is intended to address copyright-related issues
   surrounding building, installing and using a package, and not to address
   redistribution issues (see RESTRICTED and NO\_PUBLIC\_SRC, etc.). Packages
   with redistribution restrictions should set these tags.

\end{description}


Other variables affecting the build process may be gathered in their own
section.

\begin{description}

   \item[PKG\_SUPPORTED\_OPTIONS] is the list of build options supported by the
   package. A number of related variables are used in combination with {\tt
   PKG\_SUPPORTED\_OPTIONS}. See \xref{section:genvars:PKG_SUPPORTED_OPTIONS}
   {Section~\ref{section:genvars:PKG_SUPPORTED_OPTIONS}} for details.

\end{description}


\subsection{distinfo} % ----------------------------------------------------
\label{subsection:distinfo}

The distinfo file contains the message digest, or checksum, of each distfile
needed for the package. This ensures that the distfiles retrieved from the
Internet have not been corrupted during transfer or altered by a malign force
to introduce a security hole. Due to recent rumor about weaknesses of digest
algorithms, all distfiles are protected using both SHA1 and RMD160 message
digests, as well as the file size.

The distinfo file also contains the checksums for all the patches found in the
patches directory (see
\xref{subsection:patches}{Section~\ref{subsection:patches}}).

To regenerate the distinfo file, use the {\tt make distinfo} or {\tt make mdi}
command.


\subsection{PLIST}
\label{subsection:PLIST}

This  file  governs the  files  that  are installed  on  your  system: all  the
binaries, manual pages, etc. There are other directives which may be entered in
this  file,  to control  the  creation and  deletion  of  directories, and  the
location of inserted files.

The  names used  in the  PLIST are  relative to  the installation  prefix ({\tt
\$\{PREFIX\}}),  which  means  that  it  cannot  register  files  outside  this
directory  (absolute path names  are not  allowed). As  a general  sanity rule,
robotpkg must  not alter  any files outside  {\tt \$\{PREFIX\}} anyway  and, in
particular, not modify automatically existing configuration files. If a package
needs  to install  files  outside {\tt  \$\{PREFIX\}},  the best  option is  to
install   them   with   robotpkg   inside  {\tt   \$\{PREFIX\}}   (e.g.    {\tt
\$\{PREFIX\}/etc} or  {\tt \$\{PREFIX\}/var}) and  create a {\tt  MESSAGE} file
that will instruct the  user to manually link or copy the  files in question to
their final location. See the package {\tt hardware/ieee1394-kmod} for an
example of such package.

In  order to  create  or  update a  {\tt  PLIST}, you  can  use  the {\tt  make
print-PLIST} command  to output  a PLIST that  matches any new  installed files
since  the  package   was  extracted.   This  command  will   generate  a  {\tt
PLIST.guess} file which  you must move manually to  {\tt PLIST} after reviewing
the result  of the semi-automatic  generation. In order  to fine tune  the {\tt
PLIST}  or  its semi-automatic  generation,  specific  variables documented  in
\xref{section:genvars:PLIST}{section~\ref{section:genvars:PLIST}} and
\xref{section:genvars:print-PLIST}{section~\ref{section:genvars:print-PLIST}}
may be used.


\subsection{patches/*} % ----------------------------------------------------
\label{subsection:patches}

Some packages may not work out-of-the box with robotpkg. Therefore, a number of
custom patch  files may be needed to  make the package work.  These patch files
are found in the {\tt patches/} directory. If you want to share patches between
multiple packages  in robotpkg, e.g. because  they use the  same distfiles, set
{\tt PATCHDIR} to the path where the patch files can be found, e.g.:
\begin{quote}
   PATCHDIR= ../../devel/boost/patches
\end{quote}

The file names of the patch files must be of the form {\tt patch-*}, and they
are usually named {\tt patch-[a-z][a-z]}. In  the {\em  patch} phase,  these
patches  are automatically applied  to the  files  in {\tt \$\{WRKSRC\}}
directory after extracting them, in alphabetic order.

The {\tt patch-*} files should be in {\tt diff -bu} format, and apply without a
fuzz to avoid problems.  (To force patches to apply with fuzz  you can set {\tt
PATCH\_FUZZ\_FACTOR=-F2} in a package's {\tt Makefile}).

Each patch file should be commented so that any developer who knows the code of
the application  can make some use of  the patch. Special care  should be taken
for the upstream developers, since  we generally want that they accept robotpkg
patches, so there is less work in the future. When adding a patch that corrects
a problem in the distfile (rather than e.g. enforcing robotpkg's view of where
man pages should go), send the patch as a bug report to the maintainer. This
benefits non-robotpkg users of the package, and usually makes it possible to
remove the patch in future version.

When you add or modify existing patch files, remember to generate the checksums
for the patch files by using the {\tt make mdi} command, see
\xref{subsection:distinfo}{Section~\ref{subsection:distinfo}}.
